<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
In-memory Streams
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot059.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot057.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot061.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc152">10.3</A>&nbsp;&nbsp;In-memory Streams</H2><UL>
<LI><A HREF="umsroot060.html#toc94">String Streams</A>
<LI><A HREF="umsroot060.html#toc95">Queue streams</A>
</UL>

There are two kinds of in-memory streams, string streams and queues.
String streams behave much like files, they can be read, written,
positioned etc, but they are implemented as buffer in memory.
Queues are intended mainly for message-passing-style communication
between ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>and a host language, and they are also implemented as
memory buffers.<BR>
<BR>
<A NAME="toc94"></A>
<H3 CLASS="subsection"><A NAME="htoc153">10.3.1</A>&nbsp;&nbsp;String Streams</H3>
<A NAME="stringio"></A>
In ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> it is possible to associate a stream with a Prolog string
in its memory, and this string is then used in the same way as a file
for the input and output operations.
A string stream is opened like a file by the <A HREF="../bips/kernel/iostream/open-3.html"><B>open/3</B></A><A NAME="@default603"></A> predicate call
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
open(string(InitString), Mode, Stream)
</PRE></BLOCKQUOTE>
where <I>InitString</I> can be a ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> string or a variable and represents
the initial contents of the string stream.
If a variable is supplied for <I>InitString</I>, the initial value of the string
stream is the empty string and the variable is bound to this value:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 1]: open(string(S), update, s).
S = ""
yes.
</PRE></BLOCKQUOTE> 
Once a string stream is opened, all predicates using streams
can take it as argument and perform I/O on it.
In particular the predicates
<A HREF="../bips/kernel/iostream/seek-2.html"><B>seek/2</B></A><A NAME="@default604"></A> and
<A HREF="../bips/kernel/iostream/at-2.html"><B>at/2</B></A><A NAME="@default605"></A>
can be used with them.<BR>
<BR>
While writing into a stream changes the stream contents destructively,
the initial string that has been opened will never be affected.
The new stream contents can be retrieved either by reading from the string
stream, or as a whole by using
<A HREF="../bips/kernel/iostream/get_stream_info-3.html"><B>get_stream_info/3</B></A><A NAME="@default606"></A>:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 1]: S = "abcdef", open(string(S), write, s), write(s, ---).

S = "abcdef"
yes.
[eclipse 2]: get_stream_info(s, name, S).

S = "---def"
yes.
[eclipse 3]: seek(s, 1), write(s, .), get_stream_info(s, name, S).

S = "-.-def"
yes.
[eclipse 4]: seek(s, end_of_file), write(s, ine),
             get_stream_info(s, name, S).

S = "-.-define"
yes.
</PRE></BLOCKQUOTE>
<A NAME="toc95"></A>
<H3 CLASS="subsection"><A NAME="htoc154">10.3.2</A>&nbsp;&nbsp;Queue streams</H3>
<A NAME="queueio"></A>
A queue stream is opened by the <A HREF="../bips/kernel/iostream/open-3.html"><B>open/3</B></A><A NAME="@default607"></A> predicate
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
open(queue(InitString), Mode, Stream)
</PRE></BLOCKQUOTE>
The initial queue contents is <I>InitString</I>.
It can be seen as a string which gets extended at its end on writing
and consumed at its beginning on reading.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 11]: open(queue(""), update, q), write(q, hello), write(q, " wo").
yes.
[eclipse 12]: read_string(q, " ", _, X).
S = "hello"
yes.
[eclipse 13]: write(q, "rld"), read(q, X).
S = world
yes.
[eclipse 14]: at_eof(q).
yes.
</PRE></BLOCKQUOTE> 
It is not allowed to seek on a queue. Therefore, once something is read
from a queue, it is no longer accessible. A queue is considered to be
at its end-of-file position when it is currently empty, however this
is no longer the case when the queue is written again.<BR>
<BR>
A useful feature of queues is that they can raise a synchronous event
when data arrives on the empty queue. To create such an event-raising
queue, this has to be specified as an option when opening the queue with
<A HREF="../bips/kernel/iostream/open-4.html"><B>open/4</B></A><A NAME="@default608"></A>.
In the example we have chosen the same name for the stream and for the
event, which is not necessary but convenient when the same handler
is going to be used for different queues:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 1]: [user].
 handle_queue_event(Q) :-  
        read_string(Q, "", _, Data),
        printf("Queue %s received data: %s\n", [Q,Data]).
yes.
[eclipse 2]: set_event_handler(eventq, handle_queue_event/1).
yes.
[eclipse 3]: open(queue(""), update, eventq, [event(eventq)]).
yes.
[eclipse 4]: write(eventq, hello).
Queue eventq received data: hello
yes.
</PRE></BLOCKQUOTE> 
<HR>
<A HREF="umsroot059.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot057.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot061.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
